Add openapi v3 #5627

amirsalarsafaei · 2025-06-03T14:55:20Z

References to other Issues or PRs

This feature was request in #441.

Have you read the Contributing Guidelines?

Brief description of what is fixed or changed

This is a minimal implementation (as I'm writing this description a draft) for openapiv3 protoc plugin.

Other comments

I plan to add tests and complete other features. I just want to get this look at before I go all in.
Right now it generates OpenAPI spec version 3, using kin-openapi library.

johanbrandhorst

Hi, thanks for taking the time to look into this. It's going to be hard for me to review this the way it's currently written. It seems to be based a lot on the existing generator. Could you talk to me about the process you used to build this? I explicitly said that I want us to start from scratch with this generator and not rely on existing code, if we can avoid it. I would remove basically all the flags too and add them piece by piece. Did you use AI to build this?

protoc-gen-openapiv3/options/annotations.swagger.json

protoc-gen-openapiv3/options/openapiv3.swagger.json

amirsalarsafaei · 2025-06-05T20:27:02Z

Hi,
Thanks for taking a look at it.
I understood that you didn't want the core functionality to be like the existing generator. But I wanted something to get off the ground. So I copied some base stuff. I thought that you didn't want to use the open api generation method from proto. And using the registry was ok. I dont want a full review I exactly wanted to get some pointers before I fully complete the PR. So I will start by keeping the flags I need. And removing dependencies from other parts as much as possible. I used AI in the process but not for code extensively.

amirsalarsafaei · 2025-06-05T20:33:43Z

I'm also a little bit unfamiliar with bazel. I will fix the bazel config to not generate the swagger files

amirsalarsafaei · 2025-07-01T08:37:49Z

@johanbrandhorst could you please take another look at it? I deleted the borrowed parts and rewrote them.
The generator is missing nested param generation and support for /{param=foo/*}/ path templates.

amirsalarsafaei · 2025-07-01T08:38:59Z

I only implemented the flags that we use in our company for V2.

johanbrandhorst

I haven't looked at the code, but I ran a simple test:

go install ./protoc-gen-openapiv3
Add a new stanza to buf.gen.yaml for the protoc-gen-openapiv3 plugin
Run buf generate

It crashed with a stack overflow, I think you have a broken recursion somewhere. The stack trace is:

runtime: goroutine stack exceeds 1000000000-byte limit
runtime: sp=0x4020c00380 stack=[0x4020c00000, 0x4040c00000]
fatal error: stack overflow

runtime stack:
runtime.throw({0x55bc01?, 0x3b1b8?})
        /usr/local/go/src/runtime/panic.go:1096 +0x38 fp=0x40000ade70 sp=0x40000ade40 pc=0x7ecc8
runtime.newstack()
        /usr/local/go/src/runtime/stack.go:1107 +0x45c fp=0x40000adfb0 sp=0x40000ade70 pc=0x65cbc
runtime.morestack()
        /usr/local/go/src/runtime/asm_arm64.s:342 +0x70 fp=0x40000adfb0 sp=0x40000adfb0 pc=0x83a00

goroutine 1 gp=0x40000021c0 m=4 mp=0x4000098008 [running]:
runtime.mallocgcSmallScanNoHeader(0x20?, 0x474f40?, 0x1?)
        /usr/local/go/src/runtime/malloc.go:1340 +0x344 fp=0x4020c00380 sp=0x4020c00380 pc=0x23a64
runtime.mallocgc(0x20, 0x474f40, 0x1)
        /usr/local/go/src/runtime/malloc.go:1058 +0x88 fp=0x4020c003b0 sp=0x4020c00380 pc=0x7c8b8
runtime.growslice(0x4020c004a8, 0x0?, 0x0?, 0x0?, 0x474f40)
        /usr/local/go/src/runtime/slice.go:272 +0x464 fp=0x4020c00410 sp=0x4020c003b0 pc=0x81314
github.com/grpc-ecosystem/grpc-gateway/v2/internal/descriptor.(*Message).FQMN(0x4000423ef0)
        /home/johan/src/grpc-ecosystem/grpc-gateway/internal/descriptor/types.go:101 +0x70 fp=0x4020c004c0 sp=0x4020c00410 pc=0x2ca150
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv3/internal/genopenapiv3.(*fileGenerator).generateMessageSchema(0x4040bffd40, 0x4000423ef0, {0x0, 0x0, 0x1?})
        /home/johan/src/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv3/internal/genopenapiv3/file_generator.go:72 +0x38 fp=0x4020c00750 sp=0x4020c004c0 pc=0x3e7928
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv3/internal/genopenapiv3.(*fileGenerator).generateMessageSchemaRef(0x4040bffd40, 0x4000423ef0)
        /home/johan/src/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv3/internal/genopenapiv3/file_generator.go:66 +0xf4 fp=0x4020c007d0 sp=0x4020c00750 pc=0x3e7824
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv3/internal/genopenapiv3.(*fileGenerator).generateFieldTypeSchema(0x4040bffd40, 0x400042f200, {0x4010912140, 0x28})
        /home/johan/src/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv3/internal/genopenapiv3/file_generator.go:229 +0x1b4 fp=0x4020c00840 sp=0x4020c007d0 pc=0x3e8944
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv3/internal/genopenapiv3.(*fileGenerator).generateFieldDoc(0x4040bffd40, 0x40004f0d60)
        /home/johan/src/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv3/internal/genopenapiv3/file_generator.go:203 +0x304 fp=0x4020c008b0 sp=0x4020c00840 pc=0x3e8754
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv3/internal/genopenapiv3.(*fileGenerator).generateMessageSchema(0x4040bffd40, 0x4000423ef0, {0x0, 0x0, 0x1?})
        /home/johan/src/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv3/internal/genopenapiv3/file_generator.go:88 +0x1d0 fp=0x4020c00b40 sp=0x4020c008b0 pc=0x3e7ac0
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv3/internal/genopenapiv3.(*fileGenerator).generateMessageSchemaRef(0x4040bffd40, 0x4000423ef0)
        /home/johan/src/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv3/internal/genopenapiv3/file_generator.go:66 +0xf4 fp=0x4020c00bc0 sp=0x4020c00b40 pc=0x3e7824
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv3/internal/genopenapiv3.(*fileGenerator).generateFieldTypeSchema(0x4040bffd40, 0x400042f200, {0x4010907fc0, 0x28})
        /home/johan/src/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv3/internal/genopenapiv3/file_generator.go:229 +0x1b4 fp=0x4020c00c30 sp=0x4020c00bc0 pc=0x3e8944
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv3/internal/genopenapiv3.(*fileGenerator).generateFieldDoc(0x4040bffd40, 0x40004f0d60)
        /home/johan/src/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv3/internal/genopenapiv3/file_generator.go:203 +0x304 fp=0x4020c00ca0 sp=0x4020c00c30 pc=0x3e8754
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv3/internal/genopenapiv3.(*fileGenerator).generateMessageSchema(0x4040bffd40, 0x4000423ef0, {0x0, 0x0, 0x1?})
        /home/johan/src/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv3/internal/genopenapiv3/file_generator.go:88 +0x1d0 fp=0x4020c00f30 sp=0x4020c00ca0 pc=0x3e7ac0
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv3/internal/genopenapiv3.(*fileGenerator).generateMessageSchemaRef(0x4040bffd40, 0x4000423ef0)
        /home/johan/src/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv3/internal/genopenapiv3/file_generator.go:66 +0xf4 fp=0x4020c00fb0 sp=0x4020c00f30 pc=0x3e7824
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv3/internal/genopenapiv3.(*fileGenerator).generateFieldTypeSchema(0x4040bffd40, 0x400042f200, {0x4010907e00, 0x28})
...
       /home/johan/src/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv3/internal/genopenapiv3/file_generator.go:66 +0xf4 fp=0x4040bffbe0 sp=0x4040bffb60 pc=0x3e7824
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv3/internal/genopenapiv3.(*fileGenerator).generateFileSpec(0x4040bffd40, 0x40004ee240)
        /home/johan/src/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv3/internal/genopenapiv3/file_generator.go:44 +0x288 fp=0x4040bffc70 sp=0x4040bffbe0 pc=0x3e76a8
github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv3/internal/genopenapiv3.(*generator).Generate(0x400000c2b8, {0x40004f1e00, 0x4, 0x400024d800?})
        /home/johan/src/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv3/internal/genopenapiv3/generator.go:44 +0x150 fp=0x4040bffdb0 sp=0x4040bffc70 pc=0x3ea8e0
main.main()
        /home/johan/src/grpc-ecosystem/grpc-gateway/protoc-gen-openapiv3/main.go:89 +0x72c fp=0x4040bfff40 sp=0x4040bffdb0 pc=0x3ee05c
runtime.main()
        /usr/local/go/src/runtime/proc.go:283 +0x284 fp=0x4040bfffd0 sp=0x4040bfff40 pc=0x4c064
runtime.goexit({})
        /usr/local/go/src/runtime/asm_arm64.s:1223 +0x4 fp=0x4040bfffd0 sp=0x4040bfffd0 pc=0x85c44

amirsalarsafaei · 2025-07-08T08:49:55Z

hank you for testing and reviewing this. To help me investigate, could you please provide the .proto file you used?

My own testing was done with the standard protoc command, which I expected to behave similarly to buf.gen. It seems I've missed an edge case. My leading theory is that the issue is related to a "resurrection check" from v2, which my current implementation doesn't include.

johanbrandhorst · 2025-07-08T15:52:47Z

I'm not sure exactly which proto file it is, as I said, I just ran it on the proto files in this repo (using buf generate). You can just re-run the steps I detailed. I've no idea what a "resurrection check" is.

amirsalarsafaei · 2025-07-09T10:44:25Z

I've no idea what a "resurrection check" is.

"recursion check" sorry. :)
Thank you I will look into it.

amirsalarsafaei · 2025-08-12T18:41:42Z

@johanbrandhorst Hi again,
sorry I was busy with university graduation and work.
I fixed the issue with the recursive messages and also fixed the path of generated files. I tested the buf generate command in the project and everything seemed fine. Could you take a look again? Sorry for bothering you so much:)
Best Regards

johanbrandhorst · 2025-08-12T20:05:40Z

Could you rebase this branch on main and mark this PR as ready for review please? I'm hoping it will trigger CI to run.

amirsalarsafaei · 2025-08-13T07:26:59Z

@johanbrandhorst I rebased and changed the status to waiting for review.

I believe it requires an approval to run:
This workflow is awaiting approval from a maintainer in https://github.com/grpc-ecosystem/grpc-gateway/pull/5627

johanbrandhorst

I'm confused, shouldn't there be some generated openapiv3 files?

johanbrandhorst · 2025-08-15T04:50:43Z

protoc-gen-openapiv3/internal/genopenapiv3/convertors.go

+package genopenapiv3
+
+import (
+	"github.com/getkin/kin-openapi/openapi3"


I'd prefer not to add a third party dependency like this, could we define these types ourselves?

we can. I talk about using kin-openapi before starting the implementation. The library is well maintained an other repositories like https://github.com/oapi-codegen/oapi-codegen use it as well. It think the main benefit would be in the tests where there are some cool functions like validate and JSONLookup. But if you think the cons outweigh the pros I will remove it and use our own types. The bazel was giving me hell because of it as well...

johanbrandhorst · 2025-08-15T04:51:25Z

protoc-gen-openapiv3/internal/genopenapiv3/convertors.go

+	"google.golang.org/protobuf/proto"
+
+	"github.com/grpc-ecosystem/grpc-gateway/v2/internal/descriptor"


Merge these import groups

johanbrandhorst · 2025-08-15T04:57:39Z

protoc-gen-openapiv3/options/annotations.proto

+  // ID assigned by [email protected] for
+  // gRPC-Gateway project.
+  //
+  // All IDs are the same, as assigned. It is okay that they are the same, as
+  // they extend different descriptor messages.
+  OpenAPI openapiv3_document = 1043;


If this number is the same as the protoc-gen-openapiv2, it means users can't use this together with openapiv2. We will need a new number. For now, can we use 99999, but if/when we merge this, I will request a new number from the global extension registry. See https://protobuf.dev/programming-guides/proto2/#customoptions for more information.

If this number is the same as the protoc-gen-openapiv2, it means users can't use this together with openapiv2. We will need a new number. For now, can we use 99999, but if/when we merge this, I will request a new number from the global extension registry. See https://protobuf.dev/programming-guides/proto2/#customoptions for more information.

yes sorry. I forgot to change it.

johanbrandhorst · 2025-08-15T05:00:38Z

Congratulations on your graduation by the way :)

…equest body

amirsalarsafaei · 2025-08-28T09:44:42Z

Congratulations on your graduation by the way :)

Thanks:) The post graduation paper work was holding me up sorry for the late reply

amirsalarsafaei · 2025-08-28T09:46:02Z

I'm confused, shouldn't there be some generated openapiv3 files?

The bazel image doesn't run on my ARM laptop, I have to run bazel on a x86_64 VM, I forgot to run the bazel commands I will run and push.

amirsalarsafaei · 2025-08-29T15:00:18Z

@johanbrandhorst I believe I have resolved the comments.
Could you please take another look at it.

amirsalarsafaei marked this pull request as draft June 4, 2025 18:30

johanbrandhorst requested changes Jun 5, 2025

View reviewed changes

protoc-gen-openapiv3/options/annotations.swagger.json Outdated Show resolved Hide resolved

protoc-gen-openapiv3/options/openapiv3.swagger.json Outdated Show resolved Hide resolved

NickCao mentioned this pull request Jun 6, 2025

Document HTTP API jumpstarter-dev/jumpstarter-controller#142

Open

amirsalarsafaei force-pushed the add-openapi-v3 branch 4 times, most recently from f912d21 to c827f3a Compare July 1, 2025 08:35

johanbrandhorst requested changes Jul 8, 2025

View reviewed changes

amirsalarsafaei force-pushed the add-openapi-v3 branch from c96b3bb to 93d2dcb Compare August 13, 2025 07:15

amirsalarsafaei marked this pull request as ready for review August 13, 2025 07:15

amirsalarsafaei changed the title ~~Draft: Add openapi v3~~ Add openapi v3 Aug 13, 2025

amirsalarsafaei requested a review from johanbrandhorst August 13, 2025 07:25

johanbrandhorst requested changes Aug 15, 2025

View reviewed changes

amirsalarsafaei added 6 commits August 25, 2025 23:06

feat: add open-api v3 proto3 and base folder

fe3ef7f

feat(protoc-gen-openapiv3): implemented basic component generation

5bfe2f4

chore(protoc-gen-openapiv3): rename protofile to file_options

e0b659d

chore(protoc-gen-openapiv3): refactor generator file

5e38f8c

feat: path (method & service) generation

e0001fe

chore: refactor message/enum geneation

6250279

amirsalarsafaei added 10 commits August 25, 2025 23:06

feat: add method parameter generation

a1312b0

feat: responsebody generation (default) and remove path params from r…

2a6120b

…equest body

chore: clean the convertor codes

cbbbdd4

feat: add merged spec document

3966107

feat: add visibility level filtering

8657b0b

fix: recursive protos

f6f4eca

fix: generation path and encoder indentation

88ed424

revert: option gen

de8077c

fix: default spec info

333a492

chore: better merging logic

0b40f62

amirsalarsafaei force-pushed the add-openapi-v3 branch from 93d2dcb to 0b40f62 Compare August 25, 2025 19:37

amirsalarsafaei added 3 commits August 28, 2025 13:17

chore: run bazel

ccc72da

chore: fix bazel

9c13948

run generate

12c2c78

johanbrandhorst mentioned this pull request Aug 28, 2025

Feature Request: OpenAPI 3 support #441

Open

		"google.golang.org/protobuf/proto"

		"github.com/grpc-ecosystem/grpc-gateway/v2/internal/descriptor"

Add openapi v3 #5627

Are you sure you want to change the base?

Add openapi v3 #5627

Uh oh!

Conversation

amirsalarsafaei commented Jun 3, 2025

References to other Issues or PRs

Have you read the Contributing Guidelines?

Brief description of what is fixed or changed

Other comments

Uh oh!

johanbrandhorst left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

amirsalarsafaei commented Jun 5, 2025

Uh oh!

amirsalarsafaei commented Jun 5, 2025

Uh oh!

amirsalarsafaei commented Jul 1, 2025

Uh oh!

amirsalarsafaei commented Jul 1, 2025

Uh oh!

johanbrandhorst left a comment

Choose a reason for hiding this comment

Uh oh!

amirsalarsafaei commented Jul 8, 2025

Uh oh!

johanbrandhorst commented Jul 8, 2025

Uh oh!

amirsalarsafaei commented Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

amirsalarsafaei commented Aug 12, 2025

Uh oh!

johanbrandhorst commented Aug 12, 2025

Uh oh!

amirsalarsafaei commented Aug 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

johanbrandhorst left a comment

Choose a reason for hiding this comment

Uh oh!

johanbrandhorst Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

amirsalarsafaei Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

johanbrandhorst Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

amirsalarsafaei Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

johanbrandhorst Aug 15, 2025

Choose a reason for hiding this comment

Uh oh!

amirsalarsafaei Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

johanbrandhorst commented Aug 15, 2025

Uh oh!

amirsalarsafaei commented Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

amirsalarsafaei commented Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

amirsalarsafaei commented Aug 29, 2025

Uh oh!

Uh oh!

amirsalarsafaei commented Jul 9, 2025 •

edited

Loading

amirsalarsafaei commented Aug 13, 2025 •

edited

Loading

amirsalarsafaei commented Aug 28, 2025 •

edited

Loading

amirsalarsafaei commented Aug 28, 2025 •

edited

Loading